agentdb advanced features

仓库: ruvnet/claude-flow
安装量: 42
排名: #17344

安装

npx skills add https://github.com/proffesor-for-testing/agentic-qe --skill 'AgentDB Advanced Features'
AgentDB Advanced Features
What This Skill Does
Covers advanced AgentDB capabilities for distributed systems, multi-database coordination, custom distance metrics, hybrid search (vector + metadata), QUIC synchronization, and production deployment patterns. Enables building sophisticated AI systems with sub-millisecond cross-node communication and advanced search capabilities.
Performance
<1ms QUIC sync, hybrid search with filters, custom distance metrics. Prerequisites Node.js 18+ AgentDB v1.0.7+ (via agentic-flow) Understanding of distributed systems (for QUIC sync) Vector search fundamentals QUIC Synchronization What is QUIC Sync? QUIC (Quick UDP Internet Connections) enables sub-millisecond latency synchronization between AgentDB instances across network boundaries with automatic retry, multiplexing, and encryption. Benefits : <1ms latency between nodes Multiplexed streams (multiple operations simultaneously) Built-in encryption (TLS 1.3) Automatic retry and recovery Event-based broadcasting Enable QUIC Sync import { createAgentDBAdapter } from 'agentic-flow/reasoningbank' ; // Initialize with QUIC synchronization const adapter = await createAgentDBAdapter ( { dbPath : '.agentdb/distributed.db' , enableQUICSync : true , syncPort : 4433 , syncPeers : [ '192.168.1.10:4433' , '192.168.1.11:4433' , '192.168.1.12:4433' , ] , } ) ; // Patterns automatically sync across all peers await adapter . insertPattern ( { // ... pattern data } ) ; // Available on all peers within ~1ms QUIC Configuration const adapter = await createAgentDBAdapter ( { enableQUICSync : true , syncPort : 4433 , // QUIC server port syncPeers : [ 'host1:4433' ] , // Peer addresses syncInterval : 1000 , // Sync interval (ms) syncBatchSize : 100 , // Patterns per batch maxRetries : 3 , // Retry failed syncs compression : true , // Enable compression } ) ; Multi-Node Deployment

Node 1 (192.168.1.10)

AGENTDB_QUIC_SYNC

true \ AGENTDB_QUIC_PORT = 4433 \ AGENTDB_QUIC_PEERS = 192.168 .1.11:4433,192.168.1.12:4433 \ node server.js

Node 2 (192.168.1.11)

AGENTDB_QUIC_SYNC

true \ AGENTDB_QUIC_PORT = 4433 \ AGENTDB_QUIC_PEERS = 192.168 .1.10:4433,192.168.1.12:4433 \ node server.js

Node 3 (192.168.1.12)

AGENTDB_QUIC_SYNC

true \ AGENTDB_QUIC_PORT = 4433 \ AGENTDB_QUIC_PEERS = 192.168 .1.10:4433,192.168.1.11:4433 \ node server.js Distance Metrics Cosine Similarity (Default) Best for normalized vectors, semantic similarity:

CLI

npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m cosine

API

const result

await adapter.retrieveWithReasoning
(
queryEmbedding,
{
metric:
'cosine'
,
k:
10
,
}
)
;
Use Cases
:
Text embeddings (BERT, GPT, etc.)
Semantic search
Document similarity
Most general-purpose applications
Formula
:
cos(θ) = (A · B) / (||A|| × ||B||)
Range
[-1, 1] (1 = identical, -1 = opposite) Euclidean Distance (L2) Best for spatial data, geometric similarity:

CLI

npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m euclidean

API

const result

await adapter.retrieveWithReasoning
(
queryEmbedding,
{
metric:
'euclidean'
,
k:
10
,
}
)
;
Use Cases
:
Image embeddings
Spatial data
Computer vision
When vector magnitude matters
Formula
:
d = √(Σ(ai - bi)²)
Range
[0, ∞] (0 = identical, ∞ = very different) Dot Product Best for pre-normalized vectors, fast computation:

CLI

npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m dot

API

const result

await adapter.retrieveWithReasoning
(
queryEmbedding,
{
metric:
'dot'
,
k:
10
,
}
)
;
Use Cases
:
Pre-normalized embeddings
Fast similarity computation
When vectors are already unit-length
Formula
:
dot = Σ(ai × bi)
Range
[-∞, ∞] (higher = more similar)
Custom Distance Metrics
// Implement custom distance function
function
customDistance
(
vec1
:
number
[
]
,
vec2
:
number
[
]
)
:
number
{
// Weighted Euclidean distance
const
weights
=
[
1.0
,
2.0
,
1.5
,
...
]
;
let
sum
=
0
;
for
(
let
i
=
0
;
i
<
vec1
.
length
;
i
++
)
{
sum
+=
weights
[
i
]
*
Math
.
pow
(
vec1
[
i
]
-
vec2
[
i
]
,
2
)
;
}
return
Math
.
sqrt
(
sum
)
;
}
// Use in search (requires custom implementation)
Hybrid Search (Vector + Metadata)
Basic Hybrid Search
Combine vector similarity with metadata filtering:
// Store documents with metadata
await
adapter
.
insertPattern
(
{
id
:
''
,
type
:
'document'
,
domain
:
'research-papers'
,
pattern_data
:
JSON
.
stringify
(
{
embedding
:
documentEmbedding
,
text
:
documentText
,
metadata
:
{
author
:
'Jane Smith'
,
year
:
2025
,
category
:
'machine-learning'
,
citations
:
150
,
}
}
)
,
confidence
:
1.0
,
usage_count
:
0
,
success_count
:
0
,
created_at
:
Date
.
now
(
)
,
last_used
:
Date
.
now
(
)
,
}
)
;
// Hybrid search: vector similarity + metadata filters
const
result
=
await
adapter
.
retrieveWithReasoning
(
queryEmbedding
,
{
domain
:
'research-papers'
,
k
:
20
,
filters
:
{
year
:
{
$gte
:
2023
}
,
// Published 2023 or later
category
:
'machine-learning'
,
// ML papers only
citations
:
{
$gte
:
50
}
,
// Highly cited
}
,
}
)
;
Advanced Filtering
// Complex metadata queries
const
result
=
await
adapter
.
retrieveWithReasoning
(
queryEmbedding
,
{
domain
:
'products'
,
k
:
50
,
filters
:
{
price
:
{
$gte
:
10
,
$lte
:
100
}
,
// Price range
category
:
{
$
in
:
[
'electronics'
,
'gadgets'
]
}
,
// Multiple categories
rating
:
{
$gte
:
4.0
}
,
// High rated
inStock
:
true
,
// Available
tags
:
{
$contains
:
'wireless'
}
,
// Has tag
}
,
}
)
;
Weighted Hybrid Search
Combine vector and metadata scores:
const
result
=
await
adapter
.
retrieveWithReasoning
(
queryEmbedding
,
{
domain
:
'content'
,
k
:
20
,
hybridWeights
:
{
vectorSimilarity
:
0.7
,
// 70% weight on semantic similarity
metadataScore
:
0.3
,
// 30% weight on metadata match
}
,
filters
:
{
category
:
'technology'
,
recency
:
{
$gte
:
Date
.
now
(
)
-
30
*
24
*
3600000
}
,
// Last 30 days
}
,
}
)
;
Multi-Database Management
Multiple Databases
// Separate databases for different domains
const
knowledgeDB
=
await
createAgentDBAdapter
(
{
dbPath
:
'.agentdb/knowledge.db'
,
}
)
;
const
conversationDB
=
await
createAgentDBAdapter
(
{
dbPath
:
'.agentdb/conversations.db'
,
}
)
;
const
codeDB
=
await
createAgentDBAdapter
(
{
dbPath
:
'.agentdb/code.db'
,
}
)
;
// Use appropriate database for each task
await
knowledgeDB
.
insertPattern
(
{
/ knowledge /
}
)
;
await
conversationDB
.
insertPattern
(
{
/ conversation /
}
)
;
await
codeDB
.
insertPattern
(
{
/ code /
}
)
;
Database Sharding
// Shard by domain for horizontal scaling
const
shards
=
{
'domain-a'
:
await
createAgentDBAdapter
(
{
dbPath
:
'.agentdb/shard-a.db'
}
)
,
'domain-b'
:
await
createAgentDBAdapter
(
{
dbPath
:
'.agentdb/shard-b.db'
}
)
,
'domain-c'
:
await
createAgentDBAdapter
(
{
dbPath
:
'.agentdb/shard-c.db'
}
)
,
}
;
// Route queries to appropriate shard
function
getDBForDomain
(
domain
:
string
)
{
const
shardKey
=
domain
.
split
(
'-'
)
[
0
]
;
// Extract shard key
return
shards
[
shardKey
]
||
shards
[
'domain-a'
]
;
}
// Insert to correct shard
const
db
=
getDBForDomain
(
'domain-a-task'
)
;
await
db
.
insertPattern
(
{
/ ... /
}
)
;
MMR (Maximal Marginal Relevance)
Retrieve diverse results to avoid redundancy:
// Without MMR: Similar results may be redundant
const
standardResults
=
await
adapter
.
retrieveWithReasoning
(
queryEmbedding
,
{
k
:
10
,
useMMR
:
false
,
}
)
;
// With MMR: Diverse, non-redundant results
const
diverseResults
=
await
adapter
.
retrieveWithReasoning
(
queryEmbedding
,
{
k
:
10
,
useMMR
:
true
,
mmrLambda
:
0.5
,
// Balance relevance (0) vs diversity (1)
}
)
;
MMR Parameters
:
mmrLambda = 0
Maximum relevance (may be redundant)
mmrLambda = 0.5
Balanced (default)
mmrLambda = 1
Maximum diversity (may be less relevant) Use Cases : Search result diversification Recommendation systems Avoiding echo chambers Exploratory search Context Synthesis Generate rich context from multiple memories: const result = await adapter . retrieveWithReasoning ( queryEmbedding , { domain : 'problem-solving' , k : 10 , synthesizeContext : true , // Enable context synthesis } ) ; // ContextSynthesizer creates coherent narrative console . log ( 'Synthesized Context:' , result . context ) ; // "Based on 10 similar problem-solving attempts, the most effective // approach involves: 1) analyzing root cause, 2) brainstorming solutions, // 3) evaluating trade-offs, 4) implementing incrementally. Success rate: 85%" console . log ( 'Patterns:' , result . patterns ) ; // Extracted common patterns across memories Production Patterns Connection Pooling // Singleton pattern for shared adapter class AgentDBPool { private static instance : AgentDBAdapter ; static async getInstance ( ) { if ( ! this . instance ) { this . instance = await createAgentDBAdapter ( { dbPath : '.agentdb/production.db' , quantizationType : 'scalar' , cacheSize : 2000 , } ) ; } return this . instance ; } } // Use in application const db = await AgentDBPool . getInstance ( ) ; const results = await db . retrieveWithReasoning ( queryEmbedding , { k : 10 } ) ; Error Handling async function safeRetrieve ( queryEmbedding : number [ ] , options : any ) { try { const result = await adapter . retrieveWithReasoning ( queryEmbedding , options ) ; return result ; } catch ( error ) { if ( error . code === 'DIMENSION_MISMATCH' ) { console . error ( 'Query embedding dimension mismatch' ) ; // Handle dimension error } else if ( error . code === 'DATABASE_LOCKED' ) { // Retry with exponential backoff await new Promise ( resolve => setTimeout ( resolve , 100 ) ) ; return safeRetrieve ( queryEmbedding , options ) ; } throw error ; } } Monitoring and Logging // Performance monitoring const startTime = Date . now ( ) ; const result = await adapter . retrieveWithReasoning ( queryEmbedding , { k : 10 } ) ; const latency = Date . now ( ) - startTime ; if ( latency

100 ) { console . warn ( 'Slow query detected:' , latency , 'ms' ) ; } // Log statistics const stats = await adapter . getStats ( ) ; console . log ( 'Database Stats:' , { totalPatterns : stats . totalPatterns , dbSize : stats . dbSize , cacheHitRate : stats . cacheHitRate , avgSearchLatency : stats . avgSearchLatency , } ) ; CLI Advanced Operations Database Import/Export

Export with compression

npx agentdb@latest export ./vectors.db ./backup.json.gz --compress

Import from backup

npx agentdb@latest import ./backup.json.gz --decompress

Merge databases

npx agentdb@latest merge ./db1.sqlite ./db2.sqlite ./merged.sqlite Database Optimization

Vacuum database (reclaim space)

sqlite3 .agentdb/vectors.db "VACUUM;"

Analyze for query optimization

sqlite3 .agentdb/vectors.db "ANALYZE;"

Rebuild indices

npx agentdb@latest reindex ./vectors.db Environment Variables

AgentDB configuration

AGENTDB_PATH

.agentdb/reasoningbank.db AGENTDB_ENABLED = true

Performance tuning

AGENTDB_QUANTIZATION

binary

binary|scalar|product|none

AGENTDB_CACHE_SIZE

2000 AGENTDB_HNSW_M = 16 AGENTDB_HNSW_EF = 100

Learning plugins

AGENTDB_LEARNING

true

Reasoning agents

AGENTDB_REASONING

true

QUIC synchronization

AGENTDB_QUIC_SYNC

true AGENTDB_QUIC_PORT = 4433 AGENTDB_QUIC_PEERS = host1:4433,host2:4433 Troubleshooting Issue: QUIC sync not working

Check firewall allows UDP port 4433

sudo ufw allow 4433 /udp

Verify peers are reachable

ping host1

Check QUIC logs

DEBUG

agentdb:quic
node
server.js
Issue: Hybrid search returns no results
// Relax filters
const
result
=
await
adapter
.
retrieveWithReasoning
(
queryEmbedding
,
{
k
:
100
,
// Increase k
filters
:
{
// Remove or relax filters
}
,
}
)
;
Issue: Memory consolidation too aggressive
// Disable automatic optimization
const
result
=
await
adapter
.
retrieveWithReasoning
(
queryEmbedding
,
{
optimizeMemory
:
false
,
// Disable auto-consolidation
k
:
10
,
}
)
;
Learn More
QUIC Protocol
docs/quic-synchronization.pdf
Hybrid Search
docs/hybrid-search-guide.md
GitHub
:
https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
Website
:
https://agentdb.ruv.io
Category
Advanced / Distributed Systems
Difficulty
Advanced
Estimated Time
45-60 minutes
← 返回排行榜